home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
clipper
/
subntx2.zip
/
SUBNTX.DOC
< prev
next >
Wrap
Text File
|
1990-05-24
|
20KB
|
463 lines
--------
SUBNTX()
--------
Version 2.00 - 5/24/90
Copyright 1989, 1990 Moon Microsystems
INTRODUCTION:
Subntx() is a C function called from a Clipper program to quickly
extract index elements from an existing index file, and create a
"subset" index matching some key.
Typical uses for SubNtx() include implementing a 'WHILE' clause for
dbedit, replacing or deleting groups of records, or reporting for a
certain condition. Any of these processes can be made to perform
significantly faster with SubNtx().
SYNTAX:
result_code = subntx( <main>,<sub>,<lkey>
[,<ukey> [,<pattern> [,<use_extproc> [,<num_tries_to_lock]]]])
WHERE:
<main> - is a character string (including the ".ntx" extension) or
character variable which contains the name of the existing index
from which keys are to be extracted. It will be opened in SHARED
mode if on a network. (To be sure that buffers are flushed to disk,
the <main> index should be closed via the SET INDEX TO command. (I
have heard that when a file is opened in SHARED mode, it is flushed
to disk after each write. Be careful though and check this out
yourself if you decide to not SET INDEX TO).
<sub> - is also a character string (with the ".ntx" extension) or
variable which contains the name of the 'SUB' index to be created.
It will overwrite any file with the same name.
<lkey> - is a character string or character variable which contains the
string that is compared to the keys of the <main> index. SubNtx()
is like a SEEK key with SET EXACT OFF in that it will include
partial matches in the new sub index. Example: "Moo" will match
"Moon".
<lkey> is the lower range when an optional upper range key
(discussed next) is used.
If <lkey> contains the single character '*', it will match any key
up to and including the <ukey>, if an upper key exists, otherwise it
will attempt to match everything.
Note: The '*' character in <lkey> is converted to a "" which will
match anything just as SEEK would normally. You may just use "" if
you wish but this option is added to be consistent with the same
feature of the <ukey> which MUST contain '*' to be infinite.
<ukey> - is an optional parameter which, if not an empty string "", will
be used as the upper boundary for a range. Again, partial matches
are included in the new subset index, so a range of: lkey="Loon",
ukey="Mo" will match a <main> index key of "Moon".
<ukey> can consist of the empty string "" if you don't want an upper
range but you want to use one of the other optional parameters.
<ukey> can also contain the single character '*' to indicate that
there is an infinite upper bound. This will attempt to cause a
match of the <lkey> and all keys above it. If you attempt to place
other characters after a '*' in either the <lkey> or <ukey>, they
will just be ignored.
<pattern> - is an optional character string or variable which may consist
of a combination of literal characters and spaces, zero or more
occurrences of '?', and zero or more occurrences of '*'. <pattern>
is similar to the DOS wildcard expressions with some exceptions.
<pattern> is tested against each key which matches or falls in the
range of <lkey> to <ukey>. Note that it does not waste time
comparing keys which fall outside the range, but of course an
infinite range could be specified which would then compare all keys
to the wildcard pattern.
Just as in DOS, a literal character will match itself, and '?' will
match ANY single character in that key position. Also as in DOS,
'*' will match zero or more of ANY combination of characters.
One difference with the SubNtx() <pattern> is that the pattern will
enable an exact match (as opposed to a partial match in the <lkey>
and <ukey>) unless the '*' is the last character in the pattern. A
list of examples follow:
INDEX KEY PATTERN RESULT
---------------- ----------- ------
"Color of Money " "Col*" TRUE
"Color of Money " "*Col*" TRUE
"Color of Money " "*ey " TRUE
"Color of Money " "*ey" FALSE
"Color of Money " "* *" TRUE
"Color of Money " "Color" FALSE
"Color of Money " "*of*" TRUE
"Color of Money " "*OF*" FALSE
"Color of Money " "?ol*" TRUE
"Color of Money " "*?ol*" TRUE
"Color of Money " "??lor M*" TRUE
"Color of Money " "*Mo?ey??" FALSE
"Color of Money " "*Mo?ey*" TRUE
"Color of Money " "*Mo?ey" FALSE
<use_extproc> - This is an optional logical (.T. OR .F.) parameter which,
if passed to SubNtx(), signals for SubNtx() to call a Clipper
procedure named _subeval when an index key matches or is in the
range of <lkey> to <ukey>. This procedure can determine if the key
is extracted into the sub index or not.
If the developer uses this flag, he/she must create a procedure
named _subeval() and must return a logical value back by using a
SubNtx() internal function: reteval( <true_or_false> ). If .t. is
returned, the current key in the index will be included in the new
sub index.
(The value returned with reteval is actually stored in a C static
variable so that when _subeval returns to SubNtx() the result can be
evaluated. If reteval() isn't called before _subeval is finished,
an undetermined random value will mistakenly be used in the
evaluation.)
Two other SunNtx() internal functions which are available to
_subeval are: subrec() and subkey(). They return the current index
record number and key value, respectively. A typical example of
creating _subeval follows:
condition = "rec > 100 .and. inv_date > [04/22/90]"
PROCEDURE _SUBEVAL
* Note no parameters
rec = subrec()
key = subkey() && Not used in this example
GOTO rec
reteval( &condition )
RETURN
...OR...Use a CodeBlock for the condition in Clipper 5.0
Note: To prevent an unresolved external error when not using the
_subeval procedure, there is a C function with the same name in the
SubNtx() library which just returns true. For this reason you may
get a warning about duplicate symbols, but this can be ignored. The
procedure in your code will take precedence.
Also note that using the _subeval procedure may slow down SubNtx()
considerably, due to the overhead of reading in the actual DBF
record. If only the subkey() is evaluated, it is much faster.
Either way it is probably much faster than reindexing or using a
conditional index since the sorting process has already been done
when the main index was created.
<num_tries_to_lock> - is an optional paramter which indicates the number
of times SubNtx() should try to lock the main index file for
reading. If no value is passed, the default is to try 3 times, once